.\" $Id: PAPI_set_multiplex.3,v 1.9 2004/09/29 20:16:05 terpstra Exp $
.TH PAPI_set_multiplex 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_get_multiplex \- get the multiplexing status of specified event set
PAPI_set_multiplex \- convert a standard event set to a multiplexed event set

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int PAPI_get_multiplex(int " EventSet ");"
.BI "int PAPI_set_multiplex(int " EventSet ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_get_multiplex(C_INT\  EventSet,\  C_INT\  check )
.BI PAPIF_set_multiplex(C_INT\  EventSet,\  C_INT\  check )
.fi

.SH DESCRIPTION
.B PAPI_get_multiplex
tests the state of the 
.I PAPI_MULTIPLEXING
flag in the specified event set, returning 
.I TRUE
if a PAPI event set is multiplexed, or
.I FALSE
if not.
.LP
.B PAPI_set_multiplex
converts a standard PAPI event set created by a call to 
.B PAPI_create_eventset()
into an event set capable of handling multiplexed events. This must be done 
after calling 
.B PAPI_multiplex_init()
, but prior to calling 
.B PAPI_start().
Events can be added to an event set either before or after converting it into
a multiplexed set, but the conversion must be done prior to using it as a
multiplexed set.

.SH ARGUMENTS
.I "EventSet"
--  an integer handle for a PAPI event set as created by
.BR "PAPI_create_eventset" (3)

.SH RETURN VALUES
.B PAPI_get_multiplex
returns either
.I TRUE
(positive non-zero) if multiplexing is enabled for this event set,
.I FALSE
(zero) if multiplexing is not enabled, or
.I PAPI_ENOEVST
if the specified event set cannot be found.
.LP
On success, 
.B PAPI_get_multiplex
returns
.I PAPI_OK.
On error, a non-zero error code is returned, as described below.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid, or the EventSet is already multiplexed.
.TP
.B "PAPI_ENOEVST"
The EventSet specified does not exist.
.TP
.B "PAPI_EISRUN"
The EventSet is currently counting events.
.TP
.B "PAPI_ENOMEM"
Insufficient memory to complete the operation.

.SH EXAMPLES
.nf         
.if t .ft CW
  retval = PAPI_get_multiplex(EventSet);
  if (retval > 0) printf("This event set is ready for multiplexing\n.")
  if (retval == 0) printf("This event set is not enabled for multiplexing\n.")
  if (retval < 0) handle_error(retval);
  
  retval = PAPI_set_multiplex(EventSet);
  if ((retval == PAPI_EINVAL) && (PAPI_get_multiplex(EventSet) > 0))
    printf("This event set already has multiplexing enabled\n");
  else if (retval != PAPI_OK) handle_error(retval);
.if t .ft P
.fi         

.SH BUGS
This function has no known bugs.

.SH SEE ALSO
.BR PAPI_multiplex_init "(3)," PAPI_set_opt "(3)," PAPI_create_eventset "(3)"
